home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / XRAY.ZIP / XRAY.DOC < prev   
Text File  |  1990-02-18  |  20KB  |  474 lines
  1. XRAY  by Tom Kihlken
  2. Version 1.5 - February 1990
  3.  
  4.  
  5.   XRAY is a DOS programming tool which displays informative messages about 
  6. the operating system (DOS) functions.  With XRAY, you'll be able to snoop 
  7. in on the operating systems inards and diagnose obscure programming bugs.  
  8. The high resolution timer and summary display can also help optimize your 
  9. program's I/O.  It can be used with programs written in any language and 
  10. requires no special compiler.  
  11.  
  12.   This program is shareware.  Shareware allows you to try the program out 
  13. before you buy it.  You may also make copies for your friends or post it 
  14. on another BBS.  If you like the program and want to continue using it, 
  15. you must register by sending your name, address, $15, and the version 
  16. number shown above to the following address.  You may purchase a copy of 
  17. the assembler language source code for $30.  Your support of shareware 
  18. insures continued development of good low cost software.
  19.  
  20.  
  21. Tom Kihlken
  22. 3665 McKibbon Road
  23. Saint Louis, Missouri 63114
  24.  
  25.  
  26.  
  27.   XRAY is a memory resident program which provides either a detailed 
  28. report or a summary of exactly which DOS functins (including lots of 
  29. undocumented ones) your program is making.  Whether your use it to snoop, 
  30. or to monitor you system as it crashes, you're bound to see some 
  31. surprises.  Also included is a high resolution timer which helps detect 
  32. I/O bound code which can bog down even your tightest assembler program.
  33.   If your a programmer, use XRAY to check that your program is working 
  34. efficiently (or discover why it's crashing!).  Of course it's just as easy 
  35. to spy on someone elses code to learn how it works.  With XRAY, you'll be 
  36. able to see how data base files are updated and even how some copy 
  37. protection techniques work!
  38.   XRAY works by intercepting interrupt 21h.  Each DOS function call 
  39. outputs a single line of information.  The first two items on the line are 
  40. the function number and a brief description of it (Appendix A shows a 
  41. complete list of the DOS functions).  Next, you will find any important 
  42. input parameters, such as file names, handles, buffer sizes, etc.  
  43.   Next, the actual function is performed, and its elapsed time is shown 
  44. (accurate to 0.00001 seconds!).  If the function caused any physical disk 
  45. activity, the number of sectors read or written is shown.  If the function 
  46. returns information (like a filename, directory, etc.), that is shown 
  47. next.  Finally, either a descriptive error message or "OK" is output to 
  48. indicate the result of the operation.
  49.   A summary table of all the past DOS functions is displayed when XRAY is 
  50. run with the "/T" option.  It shows the number of functions which have 
  51. ocurred, the number of sectors of disk I/O, and the total time they 
  52. required.  This table is written to standard output and may be redirected 
  53. into a file with normal DOS redirection methods.
  54.   The output may at first look complicated, but if you study it along with 
  55. a good DOS programming manual you're guaranteed to learn lots.
  56.  
  57.   You may run XRAY as many times as you like to change the options.  To 
  58. restore the defaults, just uninstall (/U) XRAY and then reinstall it.  
  59. Here is a complete list of the parameters.
  60.  
  61.         XRAY  [options] [filename]
  62.  
  63. Where the options are:
  64.  
  65.    /C = Send XRAY output to the console (this is the default mode).
  66.         The BIOS write TTY video function is used to display characters.
  67.  
  68. /Dn-m = Display only DOS function calls numbered betweem n and m (n and m
  69.     are entered in hex).  The default is to display functions numbered 
  70.         0C-FFh (except 2Eh).  By displaying only selected functions you can 
  71.         minimize the amount of output XRAY produces. You may repeat the
  72.         /D (and /I) parameter to select several ranges.
  73.  
  74.    /F = Send XRAYs output to a disk file (the default is to display the output 
  75.         on the screen).  When /D is specified, all output is internally 
  76.         buffered in a 1K buffer.  The default filename is is C:\XRAY.LOG,
  77.     but a differant name may be specified on the command line.  Be 
  78.     sure to specify the full drive, directory, and name.
  79.  
  80.    /H = Display the meaning of the optional parameters.
  81.  
  82.    /J = Causes XRAY to JMP to the original interrupt address rather than
  83.         CALLing it.  This causes the XRAY to be less obtrusive, so give
  84.     it a try if your program doesn't run normally without it.  If you
  85.     use the /J option, you won't be able to see the result code or 
  86.     the elapsed time of the call however.
  87.  
  88. /In-m = Ignore DOS function calls numbered between n and m (n and m are 
  89.         entered in hex).  The default is to ignore functions numbered 
  90.         0-0Bh and 2Eh.  By ignoring low numbered functions XRAY 
  91.         produces less output and your program will run faster. You may 
  92.         repeat the /I (and /D) parameter to ignore several ranges.
  93.  
  94.   /Kn = Use Scan code n (n is entered in hex) for the Hot key.  You can 
  95.         press ALT and the hot key to toggle XRAYs output ON and OFF. 
  96.         The default is to not use a hot-key (for maximum keyboard 
  97.         compatiblity).  See appendix B for a table of scan codes.
  98.  
  99.     Note:  You must use the /K parameter the very first time you 
  100.     install XRAY to make the hot key to work.  This prevents the
  101.         keyboard interrupt vector from being redirected if you don't
  102.     use the hot key option.
  103.  
  104.    /O = Turns XRAY OFF.  You may turn it back on with either the hot 
  105.         key or by running XRAY again from the command prompt.
  106.  
  107.   /Pn = Send XRAY output to LPTn.  The default is to display its output 
  108.     on the screen.  The printer is the best real-time output option 
  109.     since it is available up to the time of a system crash.
  110.  
  111.   /Sn = Use the shift state n (n is entered in hex) combined with the hot key
  112.         to toggle XRAYs output ON and OFF.  The default value is 8 which is
  113.         to press Alt with the hot key.  See appendix C for a table of shift
  114.         state values.
  115.  
  116.    /T = Display a summary table of all DOS function calls showing the total
  117.     number of each function, sectors of disk I/O, and total elapsed time.
  118.  
  119.    /U = Uninstall XRAY from memory (if possible).  XRAY can only be 
  120.     uninstalled if no other TSR programs (which use interrupts 9 or
  121.     21h) have been loaded.
  122.  
  123.    /V = Display function calls made by COMMAND.COM.  The default is to 
  124.         ignore these calls.  If you use the /C option, XRAY will 
  125.         produce lots of output which may not be of interest for your 
  126.         application but it's facinating to see how the command interpreter
  127.         does its thing.  When you use /V, calls from COMMAND.COM are 
  128.     marked with an asterick.
  129.  
  130.  
  131.  
  132. OUTPUT OPTIONS
  133.  
  134.   XRAY produces two types of output.  Realtime output of each DOS function 
  135. call, and a cumulative table of all the function calls which have been 
  136. made.  The cumulative table is displayed only when the /T parameter is 
  137. given.
  138.   The real-time output from XRAY is sent to either the screen, printer, or 
  139. a disk file.  Which one you choose depends on what you are using XRAY for.  
  140.   The screen is the easiest since it is fast and you can watch it easily.  
  141. Unfortunately, it usually makes a mess of the overlying applications video 
  142. output.  XRAY uses the BIOS write TTY function to drive the display.
  143.   Sending the output to a file is better for large amounts of output.  The 
  144. disadvantage of using a file is that some output is lost in the event of a 
  145. system crash (due to internal buffering).  The size of this buffer is 1K 
  146. (about 20 function calls).  
  147.   The printer is the best output method for observing a system crash since 
  148. all of the output is displayed, right up until the machine locks up.  
  149. Printing will slow down your program however and in some cases may cause 
  150. time critical programs to timeout.  XRAY uses the BIOS print character 
  151. function (INT 17h) to drive the printer.
  152.  
  153.  
  154.  
  155. ELAPSED TIME MEASUREMENT
  156.  
  157.   XRAY uses the 8253 timer/counter to measure elapsed time of DOS function 
  158. calls.  This counter is calibrated as part of the installation process 
  159. such that it measures only the actual time executing DOS code.  It is 
  160. accurate to within approximately 10 microseconds (times are displayed to 
  161. the nearest .01 millisecond).  The largest time which can be displayed is 
  162. about 450 seconds.  This shouldn't be a problem since most functions are 
  163. completed in less than a second.
  164.   To record the elapsed time, the 8253 (timer 0) is reprogrammed to mode 2 
  165. (divide by n) on every DOS call.  This doesn't affect the clock tick rate, 
  166. however it can cause a few extra ticks which make the system clock seem to 
  167. run a bit fast.  If you're concerned about restoring the time after 
  168. running XRAY, you should reboot the machine.
  169.  
  170.  
  171.  
  172. SELECTING FUNCTIONS
  173.  
  174.   Most programs make lots of calls to the operating system.  When this 
  175. happens, XRAY produces lots of output if you don't suppress some of it. An 
  176. example of this is when a program continuously reads the clock in order to 
  177. display the time on screen.  It is easy to filter out this uninteresting 
  178. stuff with XRAY, using the /D (Display)) and /I (Ignore) options.
  179.   The default setting for the filter is to ignore functions numbered lower 
  180. than 0Ch and function 2Eh.  To ignore additional functions, just use the 
  181. /In-m option.  To add functions to the filter, use /Dn-m.  You can specify 
  182. as many ranges as you like.  You can also specify a single function number 
  183. such as /I2C.  
  184.   As each range is parsed from the command tail, it takes precedence over 
  185. previous ranges, so the order in which you specify them controls how they 
  186. are combined.  Remember, you always start with the default filter (or the 
  187. existing filter if XRAY has already been installed).
  188.   Let's look at an example.  Say we're interested in the functions 3Ch to 
  189. 40h, 16h to 17h, and 4C.  The correct parameters would be:
  190.  
  191.        /I0-FF /D16-17 /D3C-40 /D4C
  192.  
  193.   Notice the first "/I" turned off everything, the next three "/D's" turn 
  194. on the ranges we want.  When selecting ranges, it's best to avoid the 
  195. console I/O functions (01h through 0Bh) since there are millions of them 
  196. in most programs.
  197.  
  198.  
  199.  
  200. I/O SECTOR COUNT
  201.  
  202.   DOS generally buffers most I/O operations in such a way that a write 
  203. request may not be passed to the disk until a full sector of data is ready 
  204. to be written.  Disk buffering and caching also affect the physical 
  205. transfer of data to the disk.
  206.   XRAY lets you observe this buffering by displaying the actual amount of 
  207. I/O in terms of number of physical sectors.  If you compare the sector 
  208. count with the elapsed time, you'll be able to determine the effective 
  209. access time of the disk in real life situations (something benchmarks 
  210. can't really do).  Be prepared for surprises here!  Remember, some I/O 
  211. commands will hit the cache (you should be using one by now) and complete 
  212. very quickly.
  213.   The sector count is obtained by intercepting the BIOS diskette interrupt 
  214. (INT 13h) and saving the number of sectors.  Disks which have their own 
  215. device driver (RAMDISKs, etc.) won't show up in the sector count if they
  216. don't use interrupt 13h.
  217.  
  218.  
  219.  
  220. USING A HOT KEY
  221.  
  222.   Normally XRAY does its job continously after installed.  You can switch 
  223. XRAY off by running it again with the /O option.  An easier method is to 
  224. specify a hot key which will toggle XRAY off and on.
  225.   To enable use of a hot key, you MUST specify a scan code (with the /K 
  226. parameter) during the initial installation.  The default scan code is 0FFh 
  227. which indicates that the keyboard interrupt vector is not to be 
  228. intercepted and the hot key is disabled.  You can change the scan code 
  229. later if you want but you MUST enable it the FIRST time XRAY is installed.
  230.   Scan codes are selected from appendix B.  You must hold down the Alt key 
  231. together with the selected hot key.  If you want a shift key other than 
  232. ALT, specify a shift mask with the /S option.  Valid shift codes are shown 
  233. in appendix C.
  234.  
  235.  
  236.  
  237. A NOTE ABOUT COMPATIBILITY
  238.  
  239.   XRAY was written to be as compatible as possible with most programs.  
  240. Like all TSR's however, there will always be some programs which may not 
  241. run correctly with it installed.  If you seem to have trouble, there are a 
  242. couple things you can try.  
  243.   First of all, remove any other TSR programs you are using (or load them 
  244. in a different order).  Second, If the hot key interfers with your 
  245. application, try a different scan code or reinstall XRAY with the hot key 
  246. disabled (by not specifying a scan code).  
  247.   Third, try the /J option.  This causes XRAY to JMP to the original 
  248. interrupt 21 address rather than CALLing it, makint it less obtrusive.  
  249. When you do this however, you won't be able to see the result code or the 
  250. elapsed time of the call however.
  251.  
  252.  
  253.  
  254. DIGGING DEEPER
  255.  
  256.   After spending a little time with XRAY, you're bound to see things 
  257. you've never heard of or don't understand.  I can't possibly explain 
  258. everything about DOS, so I'll recommend a couple good books on the 
  259. subject.
  260.  
  261.    Duncan, Ray. Advanced MS-DOS.  Redmond, Redmond, Wash.: Microsoft 
  262.     Corporation, 1986.
  263.  
  264.    Lafore, Robert. Assembly Language Primer for the IBM PC&XT.
  265.     New York: Plume/Waite, 1984.
  266.  
  267.    Scanlon, Leo J. IBM PC Assembly Language: A Guide for Programmers.
  268.     Bovie, Md.: Robert J. Brady Co. 1983.
  269.  
  270.  
  271. CHANGES FOR VERSION 1.5
  272.  
  273. 1. Added several more undocumented DOS calls.  
  274.  
  275.  
  276. CHANGES FOR VERSION 1.4
  277.  
  278. 1. Added /T parameter to display summary table.
  279. 2. The time display routine was extended to display times up to 450 
  280.    seconds.
  281.  
  282.  
  283. CHANGES FOR VERSION 1.3
  284.  
  285. 1. The default for the filter table was modified to ignore function 2Eh.
  286. 2. Extended error codes were added to the error table.
  287. 3. More parameters are shown with each functions.
  288. 4. Elapsed time is shown to the nearest .01ms (for times less than 2ms).
  289. 5. Number of disk sectors read/written is shown.
  290. 6. The "/T" option was deleted (time measurement is the default now).
  291. 7. You may specify a filename for the log file on the command line.
  292.  
  293.  
  294.  
  295. Appendix A
  296. DOS FUNCTION CALLS
  297.  
  298.   Following is a list of the DOS function calls.  For more information, 
  299. see the DOS technical reference manual.
  300.  
  301.     00h - TERMINATE PROCEDURE
  302.     01h - READ KEYBOARD WITH ECHO
  303.     02h - DISPLAY CHARACTER
  304.     03h - AUXILARY INPUT
  305.     04h - AUXILARY OUTPUT
  306.     05h - PRINT CHARACTER
  307.     06h - DIRECT CONSOLE I/O
  308.     07h - DIRECT CONSOLE INPUT
  309.     08h - READ KEYBOARD
  310.     09h - DISPLAY STRING
  311.     0Ah - BUFFERED KEYBOARD INPUT
  312.     0Bh - CHECK KEYBOARD STATUS
  313.     0Ch - FLUSH KEYBOARD BUFFER
  314.     0Dh - DISK RESET
  315.     0Eh - SELECT DEFAULT DISK
  316.     0Fh - OPEN FILE (FCB)
  317.     10h - CLOSE FILE (FCB)
  318.     11h - SEARCH FOR FIRST FILE (FCB)
  319.     12h - SEARCH FOR NEXT FILE (FCB)
  320.     13h - DELETE FILE (FCB)
  321.     14h - SEQUENTIAL READ (FCB)
  322.     15h - SEQUENTIAL WRITE (FCB)
  323.     16h - CREATE FILE (FCB)
  324.     17h - RENAME FILE (FCB)
  325.     19h - GET CURRENT DISK
  326.     1Ah - SET DISK TRANSFER ADDRESS
  327.     1Bh - GET ALLOCATION TABLE INFO FOR DEFAULT DRIVE
  328.     1Ch - GET ALLOCATION TABLE INFO FOR SPECIFIED DRIVE
  329.     21h - RANDOM READ (FCB)
  330.     22h - RANDOM WRITE (FCB)
  331.     23h - FILE SIZE (FCB)
  332.     24h - SET RELATIVE RECORD (FCB)
  333.     25h - SET VECTOR
  334.     26h - CREATE NEW PROGRAM SEGMENT
  335.     27h - RANDOM BLOCK READ (FCB)
  336.     28h - RANDOM BLOCK WRITE (FCB)
  337.     29h - PARSE FILENAME (FCB)
  338.     2Ah - GET DATE
  339.     2Bh - SET DATE
  340.     2Ch - GET TIME
  341.     2Dh - SET TIME
  342.     2Eh - SET/RESET VERIFY FLAG
  343.     2Fh - GET DATA TRANSFER AREA
  344.     30h - GET DOS VERSION NUMBER
  345.     31h - KEEP PROCESS
  346.     33h - CONTRL BREAK CHECK
  347.     34h - GET BUSY FLAG
  348.     35h - GET VECTOR
  349.     36h - GET DISK FREE SPACE
  350.     38h - GET/SET COUNTRY INFORMATION
  351.     39h - MAKE DIRECTORY
  352.     3Ah - REMOVE DIRECTORY
  353.     3Bh - CHANGE DIRECTORY
  354.     3Ch - CREATE FILE
  355.     3Dh - OPEN FILE HANDLE
  356.     3Eh - CLOSE FILE HANDLE
  357.     3Fh - READ FROM FILE/DEVICE
  358.     40h - WRITE TO A FILE/DEVICE
  359.     41h - DELETE FILE
  360.     42h - MOVE POINTER
  361.     43h - CHANGE FILE ATTRIBUTE
  362.     44h - I/O CONTROL FOR DEVICES
  363.     45h - DUPLICATE FILE HANDLE
  364.     46h - FORCE DUPLICATE FILE HANDLE
  365.     47h - GET CURRENT DIRECTORY
  366.     48h - ALLOCATE MEMORY
  367.     49h - FREE MEMORY
  368.     4Ah - MODIFY MEMORY BLOCK
  369.     4Bh - EXECUTE A PROGRAM
  370.     4Ch - TERMINATE PROGRAM
  371.     4Dh - RETRIEVE THE RETURN CODE OF A CHILD
  372.     4Eh - FIND FIRST MATCHING FILE
  373.     4Fh - FIND NEXT MATCHING FILE
  374.     50h - SET PROGRAM SEGMENT PREFIX
  375.     51h - GET PROGRAM SEGMENT PREFIX
  376.     54h - GET VERIFY SETTING
  377.     56h - RENAME A FILE
  378.     57h - GET/SET FILE DATE
  379.     59h - GET EXTENDED ERROR
  380.     5Ah - CREATE UNIQUE FILE
  381.     5Bh - CREATE NEW FILE
  382.     5Ch - LOCK/UNLOCK FILE ACCESS
  383.     5Eh - PRINTER SETUP
  384.     5Fh - DEVICE REDIRECTION FUNCTIONS
  385.     60h - GET TRUE NAME OF A FILE
  386.     61h - SET PROGRAM SEGMENT PREFIX
  387.     62h - GET PROGRAM SEGMENT PREFIX
  388.  
  389.     
  390.  
  391. Appendix B
  392. KEYBOARD SCAN CODES
  393.  
  394.   The following is a partial list of values which can used with the /K 
  395. option to specify a hot key scan code.  The keys which are described as 
  396. "KP" are on the numeric keypad on the right side of the keyboard.  Other 
  397. codes can be found in any good technical reference.
  398.   The default condition is for the hot key to be disabled.
  399.  
  400. Code   Key             Code   Key              Code     Key
  401.  
  402.  1Eh     A              01h   Esc              3Bh       F1
  403.  30h     B              02h     1              3Ch       F2
  404.  2Eh     C              03h     2              3Dh       F3
  405.  20h     D              04h     3              3Eh       F4
  406.  12h     E              05h     4              3Fh       F5
  407.  21h     F              06h     5              40h       F6
  408.  22h     G              07h     6              41h       F7
  409.  23h     H              08h     7              42h       F8
  410.  17h     I              09h     8              43h       F9
  411.  24h     J              0Ah     9              44h      F10
  412.  25h     K              0Bh     0              57h      F11
  413.  26h     L              0Ch     -              58h      F12
  414.  32h     M              0Dh     =              47h      KP7
  415.  31h     N              0Eh    BS              48h      KP8
  416.  18h     O              0Fh   TAB              49h      KP9
  417.  19h     P              1Ah     [              4Ah      KP-
  418.  10h     Q              1Bh     ]              4Bh      KP4
  419.  13h     R              1Ch    CR              4Ch      KP5
  420.  1Fh     S              2Ah   L-SHIFT          4Dh      KP6
  421.  14h     T              39h     SPACE          4Eh      KP+
  422.  16h     U              36h   R-SHIFT          4Fh      KP1
  423.  2Fh     V              33h     ,              50h      KP2
  424.  11h     W              34h     .              51h      KP3
  425.  2Dh     X              35h     /              52h      KP0   
  426.  15h     Y                                     53h      DEL 
  427.  2Ch     Z
  428.  
  429.  
  430.  
  431. Appendix C
  432. KEYBOARD SHIFT STATE MASK CODES
  433.  
  434.   The following is a list of values which can used with the /S option to 
  435. specify a hot key shift state code.  The default value for this option is 
  436. 8 (Alt key held down).  You may numerically add values to create multiple 
  437. shift conditions.  For example, "/S09" would be used to specify both the 
  438. Right shift and Alt key held down when the hot key is pressed.  Only the 
  439. four lower bits of the shift mask are used.
  440.  
  441.  
  442.    Value          Shift State
  443.  
  444.      0          No shift key needed
  445.      1          Right shift held down
  446.      2          Left shift held down
  447.      4          Ctrl key held down
  448.      8          Alt key held down
  449.  
  450.  
  451.  
  452. Appendix D
  453. IOCTL FUNCTIONS
  454.  
  455.   IOCTL (IO control for devices) functions are involked by using DOS 
  456. function 44h.  The following subfunctions are defined.
  457.  
  458.     0 - Get Device information
  459.     1 - Set device information
  460.     2 - Read character device
  461.     3 - Write character device
  462.     4 - Read block device
  463.     5 - Write block device
  464.     6 - Get input status
  465.     7 - Get output status
  466.     8 - Is device changeable?
  467.     9 - Is device local or remote?
  468.     A - Is handle local or remote?
  469.     B - Change retry count
  470.     C - Reserved
  471.     D - Generic IOCTRL request
  472.     E - Get logical drive
  473.     F - Set logical drive
  474.